
package org.xml.sax;
import java.io.IOException;


/**
 * 定义解析实体的基本接口
 *
 *如果SAX应用程序需要为外部实体实现自定义处理，则必须实现此接口，
 * 使用{{@link org.xml.sax.XMLReader#setEntityResolver setEntityResolver}方法设置。
 *
 * 然后XML读取器将允许应用程序在包含它们之前拦截任何外部实体
 * （包括外部DTD子集和外部参数实体，如果有的话）。
 *
 * 许多SAX应用程序不需要实现这个接口，但是对于从数据库或其他专用输入源构建XML文档的应用程序，
 * 或者使用URI以外的URI类型的应用程序来说，这将非常有用。
 *
 *以下解析程序将为系统提供具有系统标识符“http：www.myhost.com/today”的实体的特殊字符流：
 * <pre>
 * import org.xml.sax.EntityResolver;
 * import org.xml.sax.InputSource;
 *
 * public class MyResolver implements EntityResolver {
 *   public InputSource resolveEntity (String publicId, String systemId)
 *   {
 *     if (systemId.equals("http://www.myhost.com/today")) {
 *              // return a special input source
 *       MyReader reader = new MyReader();
 *       return new InputSource(reader);
 *     } else {
 *              // use the default behaviour
 *       return null;
 *     }
 *   }
 * }
 * </pre>
 *应用程序还可以使用此接口将系统标识符重定向到本地URI或在目录中查找替换（可能通过使用公共标识符）。
 * @since SAX 1.0
 * @author David Megginson
 * @version 2.0.1 (sax2r2)
 * @see org.xml.sax.XMLReader#setEntityResolver
 * @see org.xml.sax.InputSource
 */
public interface EntityResolver {


    /**
     * 允许应用程序解析外部实体
     *
     * 解析器将在打开除顶层文档实体以外的任何外部实体之前调用此方法。
     *
     * 这些实体包括在DTD中引用的外部DTD子集和外部参数实体（在任一种情况下，只有当分析器读取外部参数实体时）
     * 以及在文档元素内引用的外部一般实体（如果分析器读取外部一般实体）
     *
     * 应用程序可以请求解析器找到实体本身，使用替代URI，或使用应用程序提供的数据（作为字符或字节输入流）
     *
     * 用程序编写者可以使用此方法将外部系统标识符重定向到安全和/或本地URI，在目录中查找公共标识符或从数据库或其他输入源（包括例如对话框）读取实体，
     * XML和SAX都不指定使用公共或系统ID解析资源的首选策略。
     * 但是，SAX指定如何解释由此方法返回的任何输入源，
     * 如果没有返回，则系统ID将被解引用为URL。
     *
     * 如果系统标识符是一个URL，则SAX解析器必须在将其报告给应用程序之前将其完全解析。
     *
     * @param publicId 被引用的外部实体的公共标识符，如果没有提供，则返回null。
     * @param systemId 被引用的外部实体的系统标识符。
     * @return 描述新输入源的输入源对象，或者为请求解析器打开与系统标识符的常规URI连接的输入源对象。
     * @exception org.xml.sax.SAXException Any SAX exception, possibly wrapping another exception.
     * @exception java.io.IOException A Java-specific IO exception, 可能是为输入源创建新的输入流或读取器的结果
     * @see org.xml.sax.InputSource
     */
    public abstract InputSource resolveEntity (String publicId, String systemId)
            throws SAXException, IOException;

}

